home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 423_01 / recio200 / tips.txt < prev    next >
Encoding:
Text File  |  1994-04-15  |  9.7 KB  |  292 lines
  1.     Title: RECIO TIPS
  2. Copyright: (C) 1994 William Pierpoint
  3.   Version: 2.00
  4.      Date: April 15, 1994
  5.  
  6.  
  7.  
  8. 1.0 COMMON PROGRAMMING ERRORS
  9.  
  10. 1.1 Inadvertently typing a stdio function instead of a recio function
  11.  
  12. Many functions in recio and stdio have similar names and similar uses.  
  13. This makes it easier to learn the recio functions, but it also makes it 
  14. easier to unintentionally type in a stdio function when you really want a 
  15. recio function.  When compiling it is best to have all warnings turned on.  
  16. A mistyped function will give a "suspicious pointer conversion" warning; 
  17. a mistyped macro will give an "undefined symbol" error.  Exceptions: 
  18. no error or warning if you use the fcloseall function instead of the 
  19. rcloseall function, or strerror instead of rstrerror.  Hint: in most 
  20. cases you can use the rerrstr function instead of rstrerror.
  21.  
  22. 1.2 Inadvertently typing the wrong symbolic name for an error constant
  23.  
  24. Symbolic names for error constants are similar between recio and those 
  25. supported by the compiler.  You may have typed ENOMEM when you meant 
  26. R_ENOMEM.  Check to make sure that for valid record pointers, symbolic 
  27. error constants start with "R_"; for invalid record pointers, symbolic 
  28. error constants start with "E".
  29.  
  30.  
  31.  
  32. 2.0 ERROR HANDLING
  33.  
  34. 2.1 Callback Error Function
  35.  
  36. The first use of any recio function should be rseterrfn() to register 
  37. your callback error function for your application.
  38.  
  39.  
  40. 2.2 Explicit Conditions Not Reported to Callback Error Function
  41.  
  42. There are two conditions that your code must explicitly handle as 
  43. these are not reported as errors to the callback error function:
  44.  
  45. 1)  Test ropen() for NULL return and, if true, test errno for ENOENT.  
  46. This indicates that the file could not be opened since it does not exist.  
  47. Any other errors are reported to the callback error function (if registered); 
  48. your code can handle them there.
  49.  
  50.     REC *rp = ropen("file", "r");
  51.     if (!rp) {
  52.         if (errno == ENOENT) {
  53.         /* file does not exist */
  54.         ...
  55.         }
  56.     }
  57.  
  58. 2)  Test the return value from rgetrec().  If it is a NULL return, then 
  59. either end-of-file reached or an error occurred.  You need to follow up on 
  60. the NULL return value to determine which one happened.  You can use either 
  61. the reof or the rerror function.  Any errors would have been reported to the 
  62. callback error function; be careful that you don't report the same error 
  63. twice.
  64.  
  65.     /* loop through all records in file */
  66.     while (rgetrec(rp)) {
  67.         ...
  68.     }
  69.     if (!reof(rp)) {
  70.         /* error occurred before all records read */
  71.         ...
  72.     }
  73.  
  74.  
  75. 2.3 Make an Error Check Just Prior to the rclose Function
  76.  
  77. Check for errors just before closing any record stream.  This is a good 
  78. safety check since (1) you might have forgotten to install your callback 
  79. error function or (2) your callback error function failed to catch and 
  80. correct all the errors.
  81.  
  82.     if (rerror(rp)) {
  83.         /* file not completely read in */
  84.         ...
  85.     }
  86.     rclose(rp);
  87.  
  88. If you use recin in your program, check for errors after your last use of 
  89. recin or just before you exit your program.
  90.  
  91.     if (rerror(recin)) {
  92.         /* error occurred on recin stream */
  93.         ...
  94.         exit(EXIT_FAILURE);
  95.     }
  96.     exit(EXIT_SUCCESS);
  97.  
  98.  
  99. 2.4 The rsetfldstr Function Clears Error and End-of-File Indicators
  100.  
  101. The rsetfldstr function has a side effect in that it internally calls 
  102. the rclearerr function, which clears the error and end-of-file indicators.  
  103. The rationale for this is as follows:  
  104.  
  105.     1. The rsetfldstr function is used in the callback error function to 
  106.        correct data errors.  Even if used elsewhere it's purpose is to 
  107.        force-feed a data value to the program.
  108.        
  109.     2. When the callback error function returns, the recio library 
  110.        functions will only read the replacement value if the error 
  111.        and end-of-file indicators are clear.
  112.     
  113.  
  114.  
  115. 3.0 FIELDS
  116.  
  117. 3.1 Field and Text Delimiters
  118.  
  119. Field separator and text delimiter characters must be ASCII, but not
  120. the null character as the C language uses it to mark the end of a string.
  121.  
  122. If a delimiter is set to the space character, it is taken to mean any
  123. white space: space, tab, etc.  See the documentation that comes with your 
  124. compiler for the isspace() function.
  125.  
  126. Delimiters around text are optional; no error is generated if they are 
  127. missing.  However text delimiters are needed if the string contains a 
  128. field separator character.  Also no harm is done if text delimiters 
  129. are put around non-text fields.
  130.  
  131. Field and text delimiters apply only to character delimited fields.
  132.  
  133.  
  134. 3.2 String Fields
  135.  
  136. Empty strings are legal; no error is generated if there is nothing in a 
  137. string field.  All other types of fields must have something in them or 
  138. a missing data error is generated.
  139.  
  140. If you do this:
  141.  
  142.     /* usually bad */
  143.     char *strptr = rgets(rp);
  144.  
  145. strptr points to the string buffer which changes every time a new field 
  146. is read.  Instead copy the data into your string.  But the method below 
  147. could truncate your data if the field buffer has expanded.
  148.  
  149.     char str[FLDBUFSIZ+1];
  150.     
  151.     /* could lose data if field buffer expands */
  152.     strncpy(str, rgets(rp), FLDBUFSIZ);
  153.     str[FLDBUFSIZ] = '\0';
  154.  
  155. Instead you will need to dynamically allocate memory space for your strings.  
  156. If you look at TESTCH.C, you will find the scopys function, which you can use 
  157. for dynamic string copying.  If you use scopys, don't forget to (1) set all 
  158. string pointers to NULL when declaring them, and (2) free your strings when 
  159. finished with them.
  160.  
  161.     char *str=NULL;
  162.     
  163.     scopys(str, rgets(rp));
  164.     ...
  165.     free(str);
  166.     return EXIT_SUCCESS;
  167.  
  168.  
  169.  
  170. 4.0 FINE TUNING
  171.  
  172. 4.1 Better Use of Heap Space
  173.  
  174. If you are tight on memory, you can fine tune recio for your application 
  175. by doing the following:
  176.  
  177. 1. Set ROPEN_MAX to the minimum number of files you need open simultaneously.
  178.    Note that recin is always open and must be included in the count.
  179.  
  180. 2. Use rsetfldsiz() and rsetrecsiz() functions to set the maximum size 
  181.    record and field needed for that record stream.  Use these functions 
  182.    before the first field or record is read from the file.  To determine 
  183.    the maximum size record buffer, determine the number of characters in 
  184.    the longest line of the file to be read, including the newline.  To 
  185.    determine the maximum size field buffer, determine the number of 
  186.    characters in the longest field in the record.  If the longest field 
  187.    contains text delimiters, a trailing field delimiter, or white space 
  188.    between the trailing text delimiter and the trailing field delimiter, 
  189.    include these as part of the size.
  190.  
  191.  
  192.  
  193. 5.0 IDEAS FOR EXPANDED CAPABILITIES
  194.  
  195.  
  196. 5.1 Additional Types of Input Functions
  197.  
  198. The macros rget_fn, rcget_fn, etc are used to define functions that get 
  199. numerical input.  By developing the appropriate conversion functions, 
  200. one could expand recio to get other types of data, such as time, date, 
  201. etc.
  202.  
  203.  
  204. 5.2 Wrapper Functions and Macros
  205.  
  206. If you define wrapper functions or macros that supply a default value 
  207. when the record pointer is NULL, then you can combine reading the file or 
  208. reading a set of default values with the same section of code.
  209.  
  210. REC *rp = ropen("file", "r");
  211. if (rp || (!rp && errno==ENOENT)) {
  212.     /* read data using wrapper functions with default value */
  213.     ...
  214.     if (rp) rclose(rp);
  215. }
  216.  
  217. 5.2.1 Default Value
  218.  
  219. If your application cannot find a data file, you may want to use a set of
  220. built-in default values.  This could be a good strategy if your application
  221. uses configuration files.  Note that wrappers will be needed on almost every 
  222. recio function that occurs after the ropen function, including rclose, 
  223. rsetrecsiz, rsetfldsiz, rsetfldch, and rsettxtch, to prevent reporting a
  224. null record pointer to your callback error function (or you will first have 
  225. to test for a null record pointer, such as "if (rp) rclose(rp)").
  226.  
  227. Example Function
  228.  
  229. The rdgeti function gets an integer from an opened data file or gets the
  230. default value if the data file has not been opened (NULL pointer).
  231.  
  232. /* if file open, read value from file; else use default value */
  233. int rdgeti(REC *rp, int default) {
  234.     return (rp ? rgeti(rp) : default);
  235. }
  236.  
  237. Example Macro
  238.  
  239. You can easily rewrite the rdgeti function as a macro.
  240.  
  241. #define rdgeti(rp, default) ((rp) ? rgeti(rp) : (default))
  242.  
  243.  
  244. 5.2.2 Validated Range
  245.  
  246. In order to validate data, you need to make certain that the value read
  247. from the file is within established limits.  You may want to add functions 
  248. that post the range values to an internal data clipboard which your callback 
  249. error function can access.  If you are letting users correct data on the 
  250. fly, convert the minimum and maximum values to strings, and post pointers 
  251. to the strings.
  252.  
  253. Example Function
  254.  
  255. The rrgeti function gets a integer and validates that the integer is within
  256. the established range.
  257.  
  258. int rrgeti(REC *rp, int min, int max) {
  259.     int result;
  260.     
  261.     result = rgeti(rp);
  262.     if (result < min || result > max) {
  263.         rseterr(rp, R_ERANGE);
  264.     }
  265.     return result;
  266. }
  267.  
  268.  
  269. 5.2.3 Default and Range
  270.  
  271. You may want to combine default value and range validation into one function.
  272.  
  273. Example Function
  274.  
  275. The rdrgeti function gets an integer from an opened data file or gets the
  276. default value if the data file has not been opened.  The function validates 
  277. that the integer is within the established range.
  278.  
  279. int rdrgeti(REC *rp, int default, int min, int max) {
  280.     int result;
  281.  
  282.     if (!rp) {
  283.         result = default;
  284.     } else {
  285.         result = rgeti(rp);
  286.     }
  287.     if (result < min || result > max) {
  288.         rseterr(rp, R_ERANGE);
  289.     }
  290.     return result;
  291. }
  292.